/**
 * 天气API服务接口
 * 统一所有天气数据源的调用标准，支持多源数据聚合
 */
public interface WeatherAPIService {
    
    /**
     * 获取API源的唯一标识符
     * @return 源标识符（如 "openweather", "weatherapi", "accuweather"）
     */
    String getSourceId();
    
    /**
     * 获取API源的显示名称
     * @return 友好的显示名称
     */
    String getDisplayName();
    
    /**
     * 检查API服务是否可用
     * @return true如果服务可用，false如果不可用
     */
    boolean isServiceAvailable();
    
    /**
     * 获取当前天气数据
     * @param location 位置信息
     * @return 当前天气数据，如果获取失败返回null
     * @throws RuntimeException 如果发生网络或API错误
     */
    WeatherData getCurrentWeather(Location location) throws RuntimeException;
    
    /**
     * 获取天气预报数据
     * @param location 位置信息
     * @param days 预报天数
     * @return 预报数据数组，如果获取失败返回null
     * @throws RuntimeException 如果发生网络或API错误
     */
    WeatherData[] getForecast(Location location, int days) throws RuntimeException;
    
    /**
     * 获取API的基础URL
     * @return API基础URL
     */
    String getBaseURL();
    
    /**
     * 获取API的请求限制信息
     * @return API限制描述字符串
     */
    String getAPILimits();
    
    /**
     * 检查位置是否受支持
     * @param location 位置信息
     * @return true如果位置受支持，false否则
     */
    boolean isLocationSupported(Location location);
    
    /**
     * 获取服务的优先级（用于多源聚合时的排序）
     * @return 优先级数值，数值越低优先级越高
     */
    int getPriority();
    
    /**
     * 测试API连接和延迟
     * @return 延迟时间（毫秒），如果连接失败返回-1
     */
    long testConnection();
    
    /**
     * 获取API的可用状态信息
     * @return API状态信息
     */
    APISourceInfo.APIStatus getAPIStatus();
} 